home *** CD-ROM | disk | FTP | other *** search
/ MACD 5 / MACD 5.bin / workbench / libs / shadowlib.lha / shadow / Docs / Glossary.doc < prev    next >
Text File  |  1992-11-13  |  12KB  |  275 lines
  1.                        Shadow Development Documentation
  2.                             Library Version 5.0
  3.  
  4.                               By David Navas
  5.                          Updated:  13 Nov 1992
  6.  
  7.                       Copyright © 1992 by David Navas
  8.                             All Rights Reserved
  9.  
  10.  
  11.                                  GLOSSARY
  12.      ATTR_*
  13.           A reference to a particular attribute.  An object's attributes
  14.           are documented in the object's class description in the
  15.           ShadowLibMethods.doc file.
  16.  
  17.      Attribute
  18.           A variable or structure stored at a particular offset inside of
  19.           an object.  The offset and  other information about attributes
  20.           are stored in the class definition in the class->meta_attributes
  21.           field.  Attributes are qsorted by the unique string address of
  22.           the attribute (#defined as an ATTR_....)
  23.  
  24.           Attributes can also have a default object structure which is the
  25.           default value (or values for an attribute which is a structure)
  26.           that all objects containing this attribute take on.
  27.  
  28.           All attributes are created by using the AttributeTag structure
  29.           which is passed into the METHOD_META_SUB or METHOD_META_INIT
  30.           method defined for METACLASS.  Refer to the method definitions
  31.           in ShadowLibMethods.doc for documentation on these methods.
  32.  
  33.      AutoResource
  34.           An object which has been stuck on a process' ATTR_RESOURCETREE or
  35.           ATTR_RESOURCESTACK.
  36.  
  37.           The ATTR_RESOURCETREE is freed during the process'
  38.           METHOD_META_REMOVE method, the process' METHOD_META_DESTROY
  39.           method, and once at the finish of RemoveThread(), or for each
  40.           ^C received inside of RemoveThread().
  41.  
  42.           The ATTR_RESOURCESTACK is freed only at the finish of
  43.           RemoveThread().  This implies that the resources on the
  44.           ATTR_RESOURCESTACK must not reference the process, as
  45.           RemoveThread() does not get this far until there are no
  46.           references on a process' object.
  47.  
  48.           When these resources are freed, they are sent a
  49.           METHOD_META_REMOVE and are then dropped from the tree.
  50.           Notification of this removal is NOT sent.
  51.  
  52.      AVL Trees
  53.           Automatically balancing binary trees which SHADOW uses
  54.           throughout most of the system.  Two notable exceptions are: one,
  55.           the system string code, and two, the semaphore code.  While both
  56.           of these systems do store various elements on a binary tree,
  57.           they are NOT AVL trees, and, in fact, the system string code
  58.           has the right and left child pointer reversed!  ;)
  59.  
  60.           My A3000 can store and remove about 3500 objects per second from
  61.           the AVL tree subsystem.  These AVL trees are semaphored for
  62.           correct behaviour in a multi-threaded environment.
  63.  
  64.      Binary Trees
  65.      BinTree
  66.           See: AVL Trees
  67.  
  68.      Browser
  69.           A cute class browser which allows you to see classes, meta,
  70.           methods, attributes, and instances of the objects which exist as
  71.           system elements (ie: objects which have had a METHOD_META_INIT
  72.           sent to them, but not yet a METHOD_META_REMOVE).
  73.  
  74.      Class
  75.           Used in two ways:
  76.              First, as an instance of METACLASS.
  77.              Second, as any formal description of the methods and
  78.                      attributes of an object.
  79.  
  80.           For the first, the word should be capitilized: Class.
  81.           For the second, the word should be lower-case: class,
  82.                                     and is often quoted: 'class'
  83.  
  84.      Cluster
  85.           Instance of METACLUSTER.  A description whose instances are
  86.           composites.  Describes an object (in particular, a composite)
  87.           which contains a tree of objects.  The Cluster allocates a
  88.           number of objects to reside initially on those trees when the
  89.           composite is INIT'd during the METHOD_META_INIT call.
  90.  
  91.           Probably obvious, but the Cluster keeps an array of Classes
  92.           which it instantiates and stuffs into the Composite's
  93.           ATTR_BAG binary tree.
  94.  
  95.      Composite
  96.           Instance of a Cluster.  May want to refer to the docs on the
  97.           ROOTCLUSTER (ShadowLibMethods.doc).
  98.           Has an ATTR_BAG attribute which is a binary tree where the
  99.           composite's objects are stored.
  100.  
  101.      Director
  102.           See: Watcher
  103.  
  104.      Inheritence
  105.           The process by which instances of classes gain the attributes
  106.           and methods of instances of other classes.  In the object-
  107.           oriented world, this is typically done by sub-classing
  108.           existing classes.  See sub-classing for more details.
  109.  
  110.      Instantiation Hierarchy
  111.           The relationship between an object and its cob_class.  An
  112.           object's cob_class holds a pointer to another object that holds
  113.           the blueprints to the first object.  IE: informally, its class.
  114.           Under SHADOW, this Hierarchy is a maximum of three objects deep:
  115.  
  116.                                     +----+
  117.                                     |    |
  118.                                     V    |
  119.                                    Meta--+
  120.                                     ^
  121.                                     |
  122.                                     |
  123.                                   Class
  124.                                     ^
  125.                                     |
  126.                                     |
  127.                                  Instance
  128.           An instance's cob_class points to a Class and a Class' cob_class
  129.           points to a Meta.  A Meta's cob_class points to itself.  IE:
  130.           a Meta describes itself as well as its instances (Classes).
  131.  
  132.      Meta
  133.           A 'class' which is an instance of itself, or (saying the same
  134.           thing) a meta is a class which describes itself.  This is
  135.           necessary because all classes are an object, and all objects
  136.           have a descriptive class.
  137.  
  138.           When capitilized, it usually refers to a particular meta --
  139.           like METACLASS and METACLUSTER.
  140.  
  141.      METHOD_*
  142.           A reference to a particular method.  An object's methods
  143.           are documented in the object's class description in the
  144.           ShadowLibMethods.doc file.
  145.  
  146.      Method
  147.           A function called as a function or via a message.  The function
  148.           address and other information about methods are stored in the
  149.           class definition in the class->meta_attributes field.  Methods
  150.           are qsorted by the unique string address of the method
  151.           (#defined as a METHOD_....)
  152.  
  153.           Methods can also be patched, so that one method call might
  154.           actually end up calling several different functions, in several
  155.           different ways (via a sybc. message, and via another async call,
  156.           for instance).  All of the patches on all of the methods defined
  157.           in a particular class are stored in the ATTR_PATCHEDVERBS
  158.           watched-list.
  159.  
  160.           All methods are created by using the MethodTag structure which
  161.           is passed into the METHOD_META_SUB or METHOD_META_INIT method
  162.           defined for METACLASS.  Refer to the method definitions in
  163.           ShadowLibMethods.doc for documentation on these methods.
  164.  
  165.      Notification
  166.           The process by which you receive information about changes
  167.           to Watched Variables.  See: Watcher
  168.  
  169.      Object
  170.           Used in three ways:
  171.              First, as an instance of Class.
  172.              Second, as an instance of any 'class'.
  173.              Third, as a package for data.
  174.  
  175.           For the first, the word should be capitilized: Object
  176.           For the second, the word should be lower-case: object
  177.           The third usage should be apparent.
  178.  
  179.           Unfortunately, with the advent of several thousand lines of
  180.           documentation, it is impossible to ensure that all the
  181.           documentation uses this guideline.  Treat this as a quideline,
  182.           and not the absolutely authoritative source.
  183.  
  184.      Object-Oriented
  185.           Please see any other book that describes object-oriented
  186.           programming.  The subject is too broad to be covered here.
  187.  
  188.      Patch
  189.           An extra function to be called when the 'patched' method is
  190.           called.  Patches are prioritized, and the normal method is
  191.           called at patch priority 0.
  192.  
  193.      Patch-Chain
  194.           The list of patches associated with a particular method in a
  195.           particular class is called a patch-chain.  The patches are
  196.           called from high priority to 0, the regular method is then
  197.           called, and then the patches with negative priority are called.
  198.  
  199.           This behaviour can be modified by the run-time behaviour of
  200.           patches.  Please see The AutoDoc describing DJM() and all the
  201.           *_BLOCK flags for more details.
  202.  
  203.      ppIPC
  204.           Pete and Peter's Inter-Process Communication library.  A very
  205.           nice port and message implementation which I use.  Thanks
  206.           guys.
  207.  
  208.      Property
  209.           See: Attribute
  210.  
  211.      Resource Tracking
  212.           There are two main types of Resource Tracking.  One is for
  213.           shared objects, and this is the best supported in SHADOW.
  214.           Please refer to the AutoDocs for UseObject() and DropObject().
  215.  
  216.           The other kind is local resource tracking (resources which go
  217.           away when a program exits).  Please refer to the AutoDocs for
  218.           AddAutoResource() and RemoveAutoResource().  Resources added
  219.           using AddAutoResource() are freed automatically when the
  220.           program exits.  You can prevent the removal by calling
  221.           RemoveAutoResource and managing the returned object yourself.
  222.  
  223.      System String
  224.           System strings are useful for constant strings.  The system
  225.           returns a unique address for a given string, thus allowing the
  226.           search for a string in, say, an array, by a simple longword
  227.           comparison, instead of using the slower strcmp() function.
  228.  
  229.      sub-classing
  230.           A sub-class is the result of calling a METHOD_META_SUB on an
  231.           existing class.  The sub-class inherits (or gains) all of the
  232.           methods and attributes of the pre-existing class, in addition to
  233.           creating the new attributes and methods that are passed as
  234.           parameters to the METHOD_META_SUB method.  These new methods and
  235.           attributes replace whatever old descriptions were in the
  236.           pre-existing class.
  237.  
  238.           Under SHADOW, attribute definitions cannot be overrided, although
  239.           the default attribute object can be.  Method definitions can
  240.           be overrided.
  241.  
  242.           The process of creating a sub-class is referred to as sub-classing.
  243.  
  244.      sub-meta
  245.           Same as a sub-class, except that the 'class' that is being
  246.           'sub-classed' is actually a meta description.
  247.  
  248.      super-class
  249.           See: sub-class.  The pre-existing class becomes the super-class of
  250.           the sub-class.
  251.  
  252.      Tags
  253.           I use this name in a slightly different manner than AmigaDOS 2.0
  254.           does.  A 'tagged' array is a NULL-long-word-terminated array
  255.           where each element is some specific size.
  256.  
  257.           For instance, the MethodTag is 24bytes, the AttributeTag is
  258.           12bytes.
  259.  
  260.           Usually, the First long-word is some kind of specifier.  In the
  261.           case of MethodTag and AttributeTag, these specifiers are pointers
  262.           to strings.
  263.  
  264.      Unique String
  265.           See: System String
  266.  
  267.      Watcher -- WatchedVariable
  268.           An object which hooks onto a WatchedValue or WatchedTree
  269.           or WatchedList structure, and gets notification sent to it
  270.           whenever the watched structure is modified via the *Watch*
  271.           routines.  In particular, whenever the WatcherDispatch function
  272.           is called.  Please see the AutoDocs for this and other *Watch*
  273.           functions in the ShadowLibFuncs.doc documentation file.
  274.  
  275.